🤖 GitHub comments

Documentation changes preview: https://docs-v3-preview.elastic.dev/elastic/ecs/pull/2532/reference/

🔍 Preview links for changed docs

• docs/reference/ecs-gen_ai.md
• docs/reference/ecs-otel-alignment-details.md
• docs/reference/ecs-otel-alignment-overview.md
• rfcs/text/0052-gen_ai-additional-fields.md

I've updated this PR now that there have been recent changes that moves us toward using flattened fields (pending merge).

• Use flattened field root blockloader elasticsearch#144245 enables ES|QL to load flattened fields as JSON strings, queryable via JSON_EXTRACT.
• Add sub-field support to flattened field type elasticsearch#144451 "Allow specific keys within a flattened field to be mapped as typed sub-fields (keyword, ip, etc.) via a new "properties" mapping attribute."

In addition, based on previous discussions, it seems that flattened is the most feasible for the use cases we've brought up (namely to be useable with ES|QL).

1. OTel Collector ES exporter

Nested fields are not supported under passthrough namespaces like attributes.* are in the OTel ES schema.
So defining gen_ai.input.messages, gen_ai.output.messages and gen_ai.tool.definitions as nested would not be compatible with OTel ingest.
Complex attributes types are currently always mapped to flattened in the OTel Collector ES exporter.
-- @AlexanderWert

See comment.

2. Serverless limitation for nested fields on indices

"The default setting for limiting nested fields on indices (index.mapping.nested_fields.limit) is 50. If customers try to create a new index with a higher limit, they will receive the following error: Settings [index.mapping.nested_fields.limit,index.mapping.nested_objects.limit] are not available when running in serverless mode. It's a serverless limitation that can't be overridden without Elastic support involved."
-- @Mikaayenson

See comment

3. ES|QL queryability

At the time this RFC was drafted, neither nested nor flattened were supported in ES|QL. As of March 2026, the picture has changed significantly:

• flattened: Active development under way, linked at the top of this comment
• nested: No movement on tracker issue: ES|QL: support nested fields elasticsearch#107434

flattened is therefore the only path to ES|QL queryability in the foreseeable future.

There are tradeoffs, which I've captured here

"With flattened, it would not be possible to query for something like 'system role has a text like helpful bot', [...] the association between the role field and the parts.content field is lost."
— @flash1293

See comment

"We will likely lean on _source to access nested dicts in an order preserving fashion."
— @joe-desimone

See comment

This trade-off is something we will need to accept given the OTel compatibility requirement and lack of movement on nested support with ES|QL.

Hey @susan-shu-c have you checked latest changes in OTEL for genAI fields? It might be there were some renamings or deprecations etc as we have discussed this issue long time ago. So before continuing with it I would like to be sure we are on the same page with otel definitions

Hi @trisch-me all 6 fields introduced in this PR are in the newest v1.40.0 OTel with the exact same naming link

Vale Linting Results

Summary: 24 warnings found

The Vale linter checks documentation changes against the Elastic Docs style guide.

To use Vale locally or report issues, refer to Elastic style guide for Vale.

@kgeller I've addressed the feedback in #2532 please let me know if I've missed something specific!

Are we using gen_ai.system currently? it’s deprecated in semconv in favor for provider. Do we want to follow semconv or we stay with old name?

@trisch-me happy to add gen_ai.provider.name link [Edit: Added!]

If it's in the scope of this PR, how can I incorporate removing gen_ai.system (link), in this PR? [Edit: I've made the replacement, but looking for comments if that's the right way to replace a field.]